load

Type

command

Summary

Downloads the file specified by a URL to a cache where it can be used by another handler.

Syntax

load [URL] <url> [with message <callbackMessage>]

Description

Use the load command to pre-fetch a file from the Internet in order to speed up access when using it in an expression with the URL keyword.

To use a file that has been downloaded by the load command, refer to it using the URL keyword as usual. When you request the original URL, LiveCode uses the cached file automatically.

The callbackMessage is sent to the object whose script contains the load command, after the URL is loaded, so you can handle the callbackMessage to perform any tasks you want to delay until the URL has been cached. On iOS, Android and Web, four parameters are sent with the message : the URL, the URLStatus of the file, the contents of the URL or an error string and the total size of the URL in bytes. On all other platforms, two parameters are sent with the message : the URL and the URLStatus of the file.

The load command is non-blocking, so it does not stop the current handler while the download is completed. The handler continues while the load command downloads the URL in the background. You can monitor the download by checking the URLStatus function periodically.

    load URL myURL
    wait until the URLStatus of myURL is cached -- DON\'T DO THIS

The file is downloaded into a local cache. It does not remain available after the application quits; the purpose of the cache is to speed up access to the specified URL, not to store it permanently. You can use a URL even if it is not in the cache, so use of the load command is optional.

note

Cached files consume memory. To release this memory after you are finished with a URL, use the unload command to remove it from the cache.

Important

The load command is part of the Internet library on desktop platforms. To ensure that the command works in a desktop standalone application, you must include this custom library when you create your standalone. In the Inclusions pane of the Standalone Application Settings window, make sure the "Internet" script library is selected.

Cross-platform note

On iOS, Android and Web, the load command is implemented in the engine. Therefore the Internet library is not needed to ensure the command works in a standalone application. If included, the Internet library implementation will be used instead of the engine implementation.

note

When specifying URLs for iOS or Android, you must use the appropriate form that conforms to RFC 1738. Ensure that you URLEncode any username and password fields appropriately for FTP URLs.

Cross-platform note

The Web engine only supports HTTP and HTTPs protocols.

Cross-platform note

URLs fetched by the Web engine from a domain other than that of the hosting the page may be blocked by web browsers, unless the server hosting the URL sets the "Access-Control-Origin" header appropriately.

Parameters

Name	Type	Description
url		Any valid http or ftp URL.
callbackMessage		The name of a message to send after the URL is loaded.

Examples

load URL "http://www.example.com/index.html"

load URL myURL with message "downloadComplete"

load URL tMyUrl with message "myUrlDownloadFinished"

on myUrlDownloadFinished
   answer "Download Complete" with "Okay"
end myUrlDownloadFinished

Related

command: unload, libURLftpUpload, libURLDownloadToFile, get, group

control structure: function

function: libURLLastRHHeaders, URLEncode, files, libURLErrorData, URLStatus, cachedURLs

glossary: object, LiveCode custom library, application, standalone application, load, cache, command, main stack, expression, keyword, download, message, parameter, handler, Standalone Application Settings

keyword: URL, file

library: Internet library, library

message: startup, openBackground, preOpenStack, openStack, preOpenCard

property: script

Compatibility and Support

Introduced

LiveCode 1.0

OS

mac

windows

linux

ios

android

web

Platforms

desktop

server

mobile